---
section: Core Concepts
title: Adding New Utilities
slug: /docs/adding-new-utilities/
---

# Adding New Utilities

Extend xstyled with your own utilities.

<carbon-ad />

xstyled presents a large collection of utilities to style a complete website. It also exposes a powerful API to be able to create your own utilities.

## Configure xstyled

### Create your config file

To configure xstyled, create a `xstyled.config.js` file (`.ts` works too) and import the `createCss` function.

```js
// xstyled.config.js
import { createCss } from '@xstyled/...'
```

This function accepts a utility (also called generator) and returns a set of functions to style your application.

```js
// xstyled.config.js
import { createCss, system } from '@xstyled/...'

export const { css, styled, x, createGlobalStyle } = createCss(system)
```

`system` includes all xstyled built-in utilities that you can find in documentation.

### Create a custom utility

Let's say you want be able to use a new property not already exposed by xstyled, for example [border-inline](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline).

`style` function let you create the property:

```js
// utilities/border-inline.js
import { style } from '@xstyled/...'

export const borderInline = style({
  prop: 'borderInline',
})
```

### Add custom utility to your config file

`compose` let you compose utilities, by composing `system` you extend the base xstyled. You can also restrict to a smaller set of utilities if you want.

```js
import { createCss, system, compose } from '@xstyled/...'
import { borderInline } from './utilities/border-inline'

export const { css, styled, x, createGlobalStyle } = createCss(
  compose(system, borderInline),
)
```

## Utility API

### Use a custom prop

By default `prop` defines both the utility prop and the CSS property generated by the utility. You may want to use another prop, a shortname or something more explicit.

The `css` option let you distinct the prop from the CSS property.

```js
import { style } from '@xstyled/...'

export const borderInline = style({
  prop: 'bi',
  css: 'borderInline'
})

// Usage
<x.div bi="1px dotted blue" />
```

### Alias property

`prop` accepts a string or an array of strings. It makes it easy to create aliases like `margin` and `m`.

```js
import { style } from '@xstyled/...'

export const margin = style({
  prop: ['margin', 'm'],
  css: 'margin',
})

// Usage
<x.div m={1} />

// or
<x.div margin={1} />
```

### Bind property to a primitive

If your property is define by a unit or by a primitive, you should bind it to the primitive. To do that, you have to specify `themeGet`:

```js
import { style, getColor } from '@xstyled/...'

export const borderInlineColor = style({
  prop: 'borderInlineColor',
  themeGet: getColor,
})

// Usage
<y.div borderInlineColor="red-500" />
```

**Available primitives: `getAngle`, `getAnimation`, `getBorderColor`, `getBorderStyle`, `getBorderWidth`, `getBorder`, `getColor`, `getDuration`, `getFontSize`, `getFontWeight`, `getFont`, `getInset`, `getLetterSpacing`, `getLineHeight`, `getPercent`, `getPx`, `getRadius`, `getRingWidth`, `getShadow`, `getSize`, `getSpace`, `getTimingFunction`, `getTransform`, `getTransitionProperty`, `getTransition` and `getZIndex`.**

### Multi CSS properties

`css` accepts a string or an array of strings. It let you create properties like `px`.

```js
import { style } from '@xstyled/...'

export const px = style({
  prop: ['px'],
  css: ['paddingTop', 'paddingBottom'],
})
```

### Generate arbitrary style

Specify a function in `css` to define arbitrary style. It makes it easy to create advanced utility like [clearfix](https://stackoverflow.com/questions/8554043/what-is-a-clearfix#:~:text=A%20clearfix%20is%20a%20way,container%20problem%20for%20floated%20elements).

```js
import { style } from '@xstyled/...'

export const clearfix = style({
  prop: 'clearfix',
  css: () => ({
    '&::after': {
      display: 'block',
      content: '',
      clear: 'both',
    },
  }),
})
```
